Software Vault: The Gold Collection/Software Vault - The Gold Collection (American Databankers) (1993).ISO/cdr30/scr210a.zip/BURNOUT.DOC

Text File | 1993-01-23 | 21KB | 570 lines

                              V2.10 12-Jun-1985

               Burnout II Documentation
               ------------------------

    Function
    --------
    Burnout is an enhanced version of the old screen blanking
    program of the same name; its primary purpose is to blank out
    your video display after a specified length of time.  This new
    version is signifcantly enhanced over the older program; not
    only does it allow you better control over its operations, but
    it is written as a virtual device driver so that you can control
    it directly from your own programs.


    V2.10 Notes
    -----------
    This version finally adds "on demand" screen blanking.  By
    pressing the left shift key and <Ctrl> simultaneously, you can
    force the screen to blank.  The key combination can be altered
    via the new F parameter.


    Installation
    ------------
    To install burnout, follow two steps: place the file BURNDEV.SYS
    in the root directory of your boot diskette or hard disk, and
    modify the CONFIG.SYS file to include the statement
    "device=burndev.sys".

    In case you are not familiar with CONFIG.SYS: this is a small
    text file which DOS reads when booting.  It contains various
    pieces of information which DOS and other programs can use when
    setting themselves up.    Look in the root directory of your boot
    disk for the file CONFIG.SYS.  If no such file exists, just
    type:

        copy con \config.sys<Enter>
        device=burndev.sys<Enter>

    Then press Ctrl-Z (you'll see "^Z") and <Enter>, and you're
    done.

    If you already have a CONFIG.SYS file (which is likely), you
    must edit it to include the statement "device=burndev.sys".  Do
    this using your text editor or word processor in text mode (or
    Edlin, heaven forbid).    Retain all existing information, and add
    the new line.

    Now reboot your machine.  If all goes well, it will boot as
    usual.    There will be no indication that anything has happened.
    However, the screen should blank out after about ten minutes of
    inactivity.  You can clear the screen instantly by pressing the
    left shift key and <Ctrl> simultaneously.  After the screen has
    cleared, any keystroke and most video activity will restore it.


    Burnout parameters
    ------------------
    There are several ways in which you can alter the operation of
    burnout.  There is a demo program called BURNOUT.COM which you
    can use for this purpose.  Its syntax is as follows:

        burnout [count] [V+-] [H+-] [C+-]

    The parameters are as follows:

    COUNT: changes the number of clock ticks until the screen
    blanks (this is called the "reset count").  For example,

        burnout 5000

    sets the reset count to 5000.  This means that if burnout
    observes no keyboard or video activity within 5000 clock
    ticks, it will blank the screen.  On the IBM PC, there are
    about 18.2 ticks per second, so this means that the screen will
    clear after about 5000/18.2 seconds (275 seconds, or about four
    and a half minutes).  (The default value on powerup is 10800
    ticks, or about 10 minutes).  You can set the reset count
    anywhere from 1 tick (not highly recommended) to 65535 ticks
    (about an hour).

    If you set the reset count to 0, burnout will be effectively
    "deinstalled" (equivalent to the old BURNOUT /Q) until you set a
    new nonzero count.  This is useful for programs that don't get
    along with the screen blanker.

    V: This stands for Video, and tells burnout whether you want it
    to monitor video activity in adddition to keyboard activity.
    You can set either "V+" (monitor video), or "V-" (don't).  Thus,

        burnout 5000 V-

    sets the program to reset to 5000 ticks, and not to monitor
    video.    Why would you not want to monitor video?  Primarily
    because some programs continuously update the display (e.g.,
    with a ticking clock) even when they're not doing anything.  If
    you set V+, the screen would never blank.  The default setting
    is V+.    (V- is equivalent to the old "BURNOUT /K" command).

    H: This stands for Hardware, and tells burnout whether you want
    it to blank the screen by manipulating the hardware (i.e., by
    turning off the video signal), or by software (which it does by
    temporarily changing screen attributes to black-on-black, or
    nondisplay).  Some explanation is in order.

    The preferred method of blanking the screen is to do it by
    manipulating the PC's video controller.  This method is very
    fast and in general has fewer problems than the software method.
    However, it does have two problems.  First, it is nonportable:
    it doesn't work with all PC-compatibles.  Second, there have
    been reports that this method can PHYSICALLY DAMAGE a few
    non-IBM video adapters, notably the Hercules and similar cards.

    The effect of hardware blanking on the IBM Enhanced Graphics
    Adapter is as yet unclear, and I recommend that you
    use software blanking for now.    I do not claim that burnout
    fully supports the EGA as of Version 2.10.

    DO NOT USE H+ IF YOU ARE USING A HERCULES OR SIMILAR VIDEO
    ADAPTERS!!! YOU HAVE BEEN WARNED!!!

    If you ARE using a standard IBM video adapter or the equivalent,
    try H+, with a setting of about 10 seconds, to make sure it
    works:

        burnout 180 H+

    The screen should blank in about 10 seconds.  If it does not,
    you will have to use H- (which is the default [safe] setting).
    Reset burnout to some reasonable period of time, of course,
    after you have tested.

    C: This stands for Continuous Clear.  If you are using H+, you
    can skip this one, because it is ignored in hardware blanking
    mode.  As mentioned above, software blanking is achieved by
    simply changing all video attributes to nondisplay
    (black-on-black).  Now, if you are running in V- mode (not
    monitoring video), or if you are running a program which
    achieves video output by writing data directly to screen memory,
    new data will begin to appear on the screen, even though it is
    blanked.  Continuous Clear attempts to remedy this by simply
    resetting all the attributes to black-on-black every time the
    clock ticks (18 times per second).  The new data will flash on
    the screen and disappear immediately.  C- is equivalent to the
    old "BURNOUT /N" command.

    F: This stands for Forced clear.  It allows you to alter the
    key combination which will clear the screen instantly.    You will
    need these codes:

        Right shift:  1
        Left shift:   2
        Ctrl:          4
        Alt:          8

    Decide what keys you want to use (any combination is OK), and
    add up the codes.  For example, if you want the screen to clear
    when you press both shift keys, add 1 + 2.  Use the sum with the
    F parameter:

        BURNOUT F3

    If you wish to disable forced blanking, use zero:

        BURNOUT F0

    Note that the maximum valid parameter is 15 (1+2+4+8, meaning
    all four keys must be pressed).  Any parameter above 15 will be
    ignored.

            *    *    *    *

    The burnout parameters can be entered in any order; illegal
    parameters, capitalization, and separators are IGNORED.  Thus,
    the following are all equivalent:

        burnout 5000 V+ H- F6
        burnout F6v+h-5000
        burnout H+, F6, V-, 5000
        burnout 5000H-F6V+

    Obviously, you cannot enter something like:

        burnout F75000

    to set the force keys to 7 and the count to 5000.  You'd have to
    use "5000F7" or "5000, F7", etc.  In particular, note that
    "F7,5000" will NOT work.  When I said that separators are
    ignored, I meant ignored.  "F7, 5000" and "F75000" are
    identical insofar as burnout is concerned.

    If you enter a COUNT greater than 65535, you're on your own.
    You won't get what you expect.

    If you don't like the way BURNOUT.COM works, you're free to
    "roll your own"; see the next section.

    When BURNOUT is finished, it will display the current device
    status.  For example:

        Status: 09994,10000, ,C-,V+,H+

    The format of the status line is:

        Status: nnnnn,nnnnn,B,C+-,V+-,H+-

    The first number is the current number of clock ticks remaining
    till the next screen blank; the second is the reset count (in
    this case, the two numbers will be very close).  The "B", if
    present, indicates that the screen is currently Blanked (you
    won't see this after running BURNOUT).  The "C", "V", and "H"
    flags indicate the current status of Continuous Clear, Video
    monitoring, and Hardware clearing.  If the parameter is active,
    the indicator will be followed by a plus sign (+), otherwise a
    minus sign (-).  In the above example, then, the current count
    is 09994, the reset count is 10000, the screen is not blanked
    (naturally), Continous Clear is off, and Video monitoring and
    Hardware clearing are on.

    If you run burnout without any parameters, it will simply
    display status without changing anything.

    You can also include any of these parameters in the config.sys
    file so that they will be set immediately when you boot.  For
    example,

        device=burndev.sys 8000 H+ V- F5


    Using the BRNDEV device
    -----------------------
    As mentioned above, the screen blanker is implemented as a
    virtual device.  The advantage to this is that it can be
    interrogated or controlled very easily, from the DOS command
    line or from your own programs.  In fact, BURNOUT.COM is a very
    simple program which takes your command line parameters, sends
    them to the burnout device, reads the current status back from
    the device, and displays the results.  This section explains how
    to do this.

    When DOS finds the "device=burndev.sys" line in config.sys, it
    loads and installs the burndev.sys program as a virtual device.
    What this means, practically speaking, is that there is now a
    new "device" attached to your PC. You already have several
    devices installed: CON, PRN, COM1 and COM2, AUX, your disk
    drives, and possibly a RAM (or virtual) disk if you have
    installed VDISK.SYS or another disk emulator.

    The new device is known to DOS by the name "BRNDEV" (note: this
    is NOT "BURNDEV", it's "BRNDEV", no U). Like other devices, you
    can write (send information) to the device, and you can read
    (receive information) from the device.    BRNDEV is designed to
    accept certain very specific information (the burnout
    parameters) when it is written to, and to return certain very
    specific information (the burnout status) when it is read from.


    Writing to BRNDEV
    -----------------
    How do you "write" to BRNDEV?  There are many ways.  The
    simplest is to do it right from the keyboard, at the DOS prompt:

        copy con brndev<Enter>
        @8000 V-#<Enter>
        ^Z<Enter>

    The "copy con brndev" command instructs DOS that you want to
    copy input from the console device to the BRNDEV device.  The
    console input "@5000 V-#<Enter>" is copied to the burnout device
    when you hit the Ctrl-Z (end of copy) and <Enter> (execute)
    keys.  To prove it worked, type "burnout" and look at the new
    parameters; they should reflect a reset count of 8000 and no
    video monitoring.  (The significance of @ and # will be
    explained shortly.)

    Another way to write to the device would be to copy a small
    textfile to BRNDEV.  As an example, type

        copy con brndemo.txt<Enter>
        @10000V+#<Enter>
        ^Z<Enter>

    You should now have a small textfile, the contents of which are
    "@10000V+#".  To sen it to BRNDEV, just type

        copy brndemo.txt brndev
            or
        type brndemo.txt > brndev

    Run burnout to prove that the parameters have changed.

    The purpose of the "@" at the beginning of the output to BRNDEV
    is to tell the device to flush or rewind its I/O buffers.
    BRNDEV just sees a sequence of characters coming from DOS; it
    has no particular way to know when it is getting a new sequence
    of command characters.    The "@" tells it to get rid of any old,
    leftover junk and to start fresh.  Make a habit of prefixing all
    BRNDEV commands with an @ symbol.

    The "#" is the "execute" character.  It tells BRNDEV that it has
    received the whole parameter list.  Only when BRNDEV sees the #
    will it examine the parameter list and execute the commands.
    Thus, "#" should be at the end of all BRNDEV commands; something
    like "@5000 C+H-" will have no effect at all.  "#" also has a
    second purpose, which will be covered below.

    It is also possible, of course, to send commands to BRNDEV from
    high level languages or from assembler programs.  Here's a BASIC
    example:

        10 OPEN "BRNDEV" FOR OUTPUT AS #1
        20 PRINT #1, "@5000 C+ H-#";
        30 CLOSE 1

    And C (this is C86); you'd want to add some error detection:

        {
        FILE *burnout, *fopen();
        static char command[] = "@5000 C+ H-#";

            burnout = fopen("BRNDEV","w");
            fwrite(command, 1, strlen(command), burnout);
            fclose(burnout);
        }

    For an 8086 assembler example, see the source for BURNOUT.COM
    (BURNOUT.ASM), which is included in the burnout library.
    Basically, you have to open the device (filename=BRNDEV, fomode
    0 or 2), and use function 40H (FWRITE) to write bytes to the
    device using the returned handle.


    Reading from BRNDEV
    -------------------

    Unfortunately, reading from BRNDEV is not quite as simple as
    writing to it.    There's no way that I can think of to do it from
    the command line; you really need a program (I suppose you could
    CTTY BRNDEV and then reboot when the machine went crazy [just
    kidding, don't try it]).  Also, there is a bug in DOS 2.x which
    prevents you from using BASIC for this purpose (fixed under 3.0,
    however).  Under 3.0, the BASIC program would be:

        10 OPEN "BRNDEV" FOR OUTPUT AS #1
        20 PRINT #1, "@#";
        30 CLOSE 1
        40 OPEN "BRNDEV" FOR INPUT AS #1
        50 BSTAT$ = INPUT$(19,1)
        60 CLOSE 1
        70 PRINT "Burnout status is "; BSTAT$

    Note that we always write an "@#" to the device before reading
    its status.  The @'s function is described as above, to flush
    any unfinished I/O from BRNDEV's buffers.  The # is used for a
    slightly different purpose, however.  It still tells BRNDEV to
    execute any pending commands (but there are none, because the @
    just flushed them).  The second purpose of # is the key one
    here: it tells BRNDEV to prepare for a status request.    When
    BRNDEV sees the #, it examines its current status and puts the
    data into a buffer, from which it will be retrieved when it gets
    the request.  Without the preparatory #, you'll get old data.

    The significance of the "19" in the INPUT$ statement is that the
    BRNDEV status report is 19 characters long.

    Here's a C example:

        {
        FILE *burnout, *fopen();
        static char command[] = "@#";
        char status[30];

            burnout = fopen("BRNDEV","rw");
            fwrite(command, 1, strlen(command), burnout);
            fread (status, 1, 255, burnout);
            fclose(burnout);
            printf("Burnout status is %s\n", status);
        }

    Note that we requested 255 characters.    DOS, in general, will
    halt a device read when it encounters a carriage return from the
    input stream.  BRNDEV makes a habit of sending a CR after the
    last byte of the status report, so this will terminate the read
    automatically; no need to worry about the true length of the
    report.  BASIC, however, will just keep reading until it
    accumulates the requested number of characters, so you do have
    to be watchful there.  The same trick (requesting too many
    characters) will also work in assembler programs (again, see
    BURNOUT.ASM).

    Now, about that bug in DOS 2.x.  It turns out that DOS will mess
    up if you ever request a single byte from an installed character
    device, which is what BRNDEV is.  (Technically: EOF is set on
    the device, and you will not be able to do any further reads
    unless you mess with IOCTL and explicitly reset EOF.)  Thus, the
    following assembler code will NOT work under 2.x:

        mov cx,19      ; Loop for 19 bytes
    Label:
        push cx       ; Save loop count
        mov ah,3FH      ; Read from file
        mov bx,BHandle      ; BRNDEV file handle (from FOPEN)
        mov cx,1      ; One byte at a time
        mov dx,offset buf ; Where to put the data
        int 21H       ; Perform read
        (do something with the byte)
        pop cx          ; Recover loop count
        loop label      ; Loop till 19 bytes read

    The first byte will be read OK, but no further input will be
    received.  You MUST read at least 2 bytes at a time.

    This bug can be overcome in assembler and C by simply requesting
    the full status report in one read.  However, it appears that
    BASIC requests only one byte at a time, even if you use
    something like INPUT$(19,n).  Reading the second byte then
    results in a READ PAST EOF error.


    Tricks
    ------
    You can do neat stuff like waiting for the screen to burn out,
    then turning it back on:

        1  REM DEMO PROGRAM TO WAIT UNTIL SCREEN BLANKS
        2  REM
        10 OPEN "BRNDEV" FOR OUTPUT AS #1
        20 OPEN "BRNDEV" FOR INPUT AS #2
        30 WHILE NOT BURNED.OUT
        40    PRINT #1,"@#";
        50    A$ = INPUT$(19,2)
        60    BURNED.OUT = (MID$(A$,13,1) = "B")
        70 WEND
        80 BEEP: PRINT "Burned out!"
        90 CLOSE 1: CLOSE 2

    The 13th character of the status report, "B", will appear in the
    report only when the screen is blanked.

    Also, your programs can cancel burnout totally, if desired:

        1  REM DEMO PROGRAM TO DISABLE BURNOUT
        2  REM
        10 OPEN "BRNDEV" FOR OUTPUT AS #1
        20 PRINT #1,"@0#";
        30 CLOSE 1

    (I am not a BASIC programmer, so if any of these demo BASIC
    programs are dumb, someone tell me.)

    Naturally, it would be possible (and friendly) to read in the
    burnout parameters, modify them while your program is running,
    and restore the original parameters when you are done.

    You can test whether or not BRNDEV is installed in a batch file
    by using the IF EXIST function:

        if exist brndev (do something)

    If you use Seaware's Extended Batch Language, you can use this
    test instead:

        bat stateof BRNDEV
        bat if %r = 0 type BURNOUT IS INSTALLED | goto -A1
        bat type BURNOUT IS NOT INSTALLED
        bat -A1

    If you have a one-floppy machine, you can trick DOS and BAT into
    not checking the second logical drive (and stopping the batch to
    ask you to "Insert diskette for drive B") by using

        if exist a:brndev (in DOS batches)
        bat stateof A:BRNDEV (in EBL batches)

    DOS apparently doesn't care if you prefix a device name with a
    drive ID.


    Incompatibilities and Problems
    ------------------------------
    I am aware of only a few problems and interactions with other
    programs.  In order for burnout to "see" keyboard and video
    activity, active programs must use ROM BIOS (or DOS, which
    itself uses BIOS) for their keyboard input and video output.
    A few progams use neither; hence burnout never sees their
    activity, and the screen will be irrevocably blanked.  These
    programs are mostly word processors; two that I know of are
    XYWrite and WordVision.  You must disable burnout before using
    either of these ("BURNOUT 0" will do the trick).  Most people do
    this in a batch:

        burnout 0
        wv
        burnout 10000

    There are also problems with some communications programs if you
    use software blanking.    If you are performing an extended length
    file transfer the screen may blank during the transfer.
    Software blanking takes a little time, and communications input
    can be lost while it is being accomplished.  This, of course,
    messes up the transfer.  And Continuous Clear is even worse.
    The solution is to either use hardware blanking, or to disable
    burnout while transfers are taking place.  You MAY be able to
    get away with leaving burnout enabled, but disabling Continuous
    Clear (C-).

    Note that the word "BRNDEV" becomes a reserved word to DOS.  You
    cannot name any file BRNDEV (or even BRNDEV.TXT, or whatever).
    DOS won't let you do that.  If you do succeed, you won't be able
    to erase it.  This is why the driver is stored in a file named
    BURNDEV.SYS rather than BRNDEV.SYS.


    Tick chart
    ----------
    To save wear and tear on your calculator, here are some
    approximate tick counts:

        Minutes   Count
        -------   -----
           1       1100
           2       2200
           3       3275
           4       4375
           5       5450
           6       6550
           7       7650
           8       8725
           9       9825
          10      10920
          20      21850
          30      32760
          40      43680
          50      54600
          60      65520



    The Usual Suspects
    ------------------
    The author accepts no responsibility for this software
    whatsoever.  It might work, it might not.  In particular, he
    accepts no responsibility for any result of the use of the
    software, even if it results in damage to your hardware.
    By using the software, you agree to this.

    The burnout device driver (BURNDEV.SYS) and all demonstration
    programs are placed in the public domain and may be freely used
    by any individual.  You may not use them commercially.    You may
    copy and distribute the software and documentation to any other
    individual, PROVIDED that you do not charge for this.

    RECOGNIZED USERS' GROUPS may, however, charge a small fee
    (not to exceed $6) for postage and materials.

    I am interested in comments or suggestions on the usability of
    the burnout system, especially by programmers.    Contact me via
    CompuServe if possible.


              All software and documentation are

                 Copyright (c) 1985 by
                Christopher J. Dunford
               10057-2 Windstream Drive
               Columbia, Maryland 21044
               CompuServe ID 76703,2002